Using Forms With Format Objects(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Format Objects and Collection Items to Format Pages

Using Forms With Format Objects
Your application may choose to support a form that can be applied to each page in a document. This may save printing time because the form can be stored in the printer's memory and need not be sent with each page of the document. For an introduction to forms, see "Forms and Format Objects," which begins on page 3-20.
To associate a form shape and its mask shape with a format object, you use the GXSetFormatForm function. To retrieve the form and mask shapes for a particular format object, you use the GXGetFormatForm function. The shape type that you associate with a format object must be a picture shape.
The GXSetFormatForm function replaces any form previously associated with a particular format object. It increments the owner counts of the new picture shapes (by calling the GXCloneShape function) and decrements the owner count of the old picture shapes (by calling the GXDisposeShape function).
Listing 3-12 shows how to associate a form with a format object. The MyAddFormatForm function in the listing adds a form consisting of a rectangle to the format object of the current page.
Listing 3-12 Adding a form to a format object
OSErr MyAddFormatForm(MyDocumentPtr myDocument)
{  
   OSErr          err;
   long           curPage;
   gxFormat       theFormat;
   gxShape        rectShape;
   gxRectangle    pageRect;

   /* 
      Get the current format object. If it's nil, use the job's
      default format object. 
   */
   curPage = myDocument->curPage;
   theFormat = myDocument->pageFormat[curPage -1];

   if (theFormat == nil)
      theFormat = GXGetJobFormat(myDocument->documentJob, 1);

   /* 
      Create a rectangle shape to use as the format object's form. 
      Make the rectangle's frame the imageable area of the page.
   */
   GXGetFormatDimensions(theFormat, &pageRect, nil);
   rectShape = GXNewRectangle(&pageRect);
   GXSetShapeBounds(rectShape, &pageRect);
   GXSetShapePen(rectShape, ff(3));
   GXSetShapeFill(rectShape, gxClosedFrameFill);
   err = (OSErr) GXGetGraphicsError(nil);

   /* 
      Set the format object's form to a new picture shape, check
      for errors, and then dispose of the shape.
   */
   if (err == noErr)
   {
      GXSetShapeType(rectShape, gxPictureType);
      GXSetFormatForm(theFormat, rectShape, nil);
      err = GXGetJobError(myDocument->documentJob);
   }
   GXDisposeShape(rectShape);
   return err;
}